Skip to content

Document vMCP embedded auth server and upstream token injection#643

Open
jhrozek wants to merge 9 commits intomainfrom
vmcp-authserver
Open

Document vMCP embedded auth server and upstream token injection#643
jhrozek wants to merge 9 commits intomainfrom
vmcp-authserver

Conversation

@jhrozek
Copy link
Copy Markdown
Contributor

@jhrozek jhrozek commented Mar 27, 2026

Summary

  • Document the embedded authorization server for vMCP, including multi-upstream provider support and sequential authorization chaining
  • Document the upstream_inject outgoing auth strategy (vMCP-only)
  • Document subjectProviderName on token exchange for hybrid deployments
  • Update related docs to reflect multi-upstream capability and add cross-references

Closes #642

Draft: This PR is a draft because the upstream ToolHive CRD changes are not fully released yet. PRs stacklok/toolhive#4390, stacklok/toolhive#4391, and stacklok/toolhive#4394 are approved but not yet merged. This documentation should be reviewed and finalized after those PRs land.

Changes

docs/toolhive/guides-vmcp/authentication.mdx (main work):

  • Added "Upstream token injection" section (upstreamInject outgoing auth strategy)
  • Added "Token exchange with upstream tokens" section (subjectProviderName)
  • Added "Embedded authorization server" section with sequence diagram, differences from MCPServer, config skeleton, incoming auth wiring, session storage, and end-to-end example
  • Cross-references existing guides for shared content (key generation, session storage, upstream provider details) to avoid duplication

docs/toolhive/concepts/vmcp.mdx:

  • Added embedded auth server paragraph under "Authentication boundary separation"
  • Fixed "four key benefits" to "five"

docs/toolhive/concepts/backend-auth.mdx:

  • Updated "single upstream provider" to clarify it applies to MCPServer only
  • Removed outdated "chained authentication not yet supported" admonition
  • Added cross-reference to vMCP embedded auth server guide

docs/toolhive/guides-k8s/auth-k8s.mdx:

  • Added cross-reference to vMCP embedded auth server in related information

Test plan

  • npm run build passes
  • Verify YAML examples match final CRD field names after upstream PRs merge
  • Review sequence diagram accuracy against implementation
  • Test cross-references resolve correctly in rendered site

🤖 Generated with Claude Code

Copilot AI review requested due to automatic review settings March 27, 2026 16:33
@vercel
Copy link
Copy Markdown

vercel bot commented Mar 27, 2026 •
edited
Loading

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
docs-website Ready Ready Preview, Comment Apr 3, 2026 8:42pm

Request Review

Copilot AI reviewed Mar 27, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Updates ToolHive documentation to describe vMCP’s embedded authorization server capabilities (including multi-upstream flows) and how upstream tokens can be forwarded/exchanged for backend authentication, plus adds a Redis Sentinel session storage guide.

Changes:

  • Document vMCP “upstream token injection” (upstreamInject) and token exchange with upstream subject tokens (subjectProviderName).
  • Add embedded authorization server documentation for vMCP (flow, differences vs MCPServer, config examples, and end-to-end walkthrough).
  • Add a new Redis Sentinel session storage tutorial and cross-link it from related docs/sidebars.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 7 comments.

Show a summary per file
File Description
sidebars.ts Adds the new Redis session storage guide to the K8s guides sidebar.
docs/toolhive/guides-vmcp/authentication.mdx Main vMCP auth guide expansion: upstream injection, upstream-subject token exchange, and embedded auth server docs.
docs/toolhive/guides-k8s/redis-session-storage.mdx New end-to-end tutorial for Redis Sentinel-backed session storage.
docs/toolhive/guides-k8s/auth-k8s.mdx Adds a “Configure session storage” section and links to the new Redis guide.
docs/toolhive/concepts/vmcp.mdx Mentions embedded auth server support and fixes benefit count wording.
docs/toolhive/concepts/backend-auth.mdx Updates statements about upstream provider limits and adds cross-references to vMCP docs + session storage docs.

jhrozek and others added 6 commits March 31, 2026 10:59
@jhrozek @claude @tgrunnagle
Add Redis Sentinel session storage guide and TLS docs
abfa020 
Add a new how-to guide at docs/toolhive/guides-k8s/redis-session-storage.mdx
that walks through deploying Redis Sentinel as the session storage backend
for the embedded authorization server. The guide uses self-contained
Kubernetes manifests instead of the Bitnami Helm chart, which Broadcom
moved behind a paid subscription in August 2025. No maintained, freely
available Helm chart with Sentinel support exists as a replacement, so
the manifests are provided inline.

Also adds TLS configuration documentation for Redis connections (both
master and Sentinel), updates the auth-k8s guide's session storage
snippet for consistency, and resolves a merge conflict in backend-auth.mdx.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jhrozek @claude @tgrunnagle
Address PR feedback: fix placeholder and remove redirect
bc0e5f4 
Replace <REDIS_ACL_PASSWORD> with YOUR_REDIS_ACL_PASSWORD (no angle
brackets) to avoid confusing ><PLACEHOLDER> syntax in Redis ACL entries.
Remove unused vercel.json redirect since the page was never published at
the old integrations/ path.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jhrozek @claude @tgrunnagle
Document vMCP embedded auth server and upstream token injection
b6e08be 
Closes #642

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@tgrunnagle
Minor updates
9d913fe 
- ephemeral key warning
- snippet showing how to override the authorization endpoint URL when the browser-facing endpoint is on a different host
- tokenResponseMapping tip
@tgrunnagle
Address feedback
7f7a9ba 
- missing `type: external_auth_config_ref` for backend auth config
- note about requiring `jwksAllowPrivateIP` for cluster-internal addresses only
- note about redis replicas and failover
@tgrunnagle
Resolve conflicts
e3889e6
@tgrunnagle tgrunnagle marked this pull request as ready for review March 31, 2026 18:02
@jerm-dro jerm-dro self-requested a review April 1, 2026 18:21
jerm-dro
jerm-dro reviewed Apr 2, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@jerm-dro jerm-dro left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. You'll want to make sure this builds and the diagrams render well.

I have one suggestion for splitting out the content, but I'll defer to @danbarr's judgment.

@tgrunnagle tgrunnagle requested review from danbarr and jerm-dro April 3, 2026 17:29
jerm-dro
jerm-dro previously approved these changes Apr 3, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@jerm-dro jerm-dro left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rendering looks good from a quick check. Two minor suggestions inline.

docs/toolhive/concepts/vmcp.mdx
## Core value propositions

vMCP delivers four key benefits:
vMCP delivers five key benefits:
Copy link
Copy Markdown
Contributor

@jerm-dro jerm-dro Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: The paragraph added below elaborates on benefit #2 (authentication boundary separation) rather than introducing a distinct fifth benefit. The original four — reduce complexity, simplify auth, secure by default, unified management — are still the four listed. Consider reverting this to "four key benefits" or restructuring the list if the embedded auth server really is a separate value prop.

Copy link
Copy Markdown
Contributor

@tgrunnagle tgrunnagle Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems to be a fix since there were already five benefits listed

docs/toolhive/guides-vmcp/authentication.mdx
externalAuthConfigRef:
name: exchange-okta
```

Copy link
Copy Markdown
Contributor

@jerm-dro jerm-dro Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: With stacklok/toolhive#4526 (merged), the embedded auth server resolves JWKS keys in-process — so jwksAllowPrivateIP: true is no longer necessary when the issuer is the embedded auth server itself. Worth adding a note here that this flag is only needed when the OIDC issuer is an external provider resolving to a private IP, and can be omitted when using the embedded auth server's own issuer.

Copy link
Copy Markdown
Contributor

@tgrunnagle tgrunnagle Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a note

@tgrunnagle
Address feedback
6a8cf66 
- note about `jwksAllowPrivateIP: true`
@tgrunnagle tgrunnagle requested a review from jerm-dro April 3, 2026 20:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@tgrunnagle tgrunnagle tgrunnagle left review comments

Copilot code review Copilot Copilot left review comments

@danbarr danbarr Awaiting requested review from danbarr

@jerm-dro jerm-dro Awaiting requested review from jerm-dro

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Document vMCP embedded authorization server and upstream token injection

4 participants

@jhrozek @tgrunnagle @jerm-dro